Shore Side Data System (600031 and 900823) : Installation and Development
This page last changed on Mar 10, 2010 by kgomes.

Installation Instructions and Development Setup for the Shore Side Data System

Although these instructions may seem VERY long, they cover a lot of ground and with much detail. The idea was to make this as detailed as possible to make it exceptionally clear every step of the way. Some topics are somewhat lengthy to setup (like SSL), but are, in fact, very necessary for various reasons (security for the SSL case). These instructions were performed on a Apple OS X installation, but should apply to most Unix variants including Linux and OS X. See Windows Installation for an example done for USC on a Windows box.

So, without further ado, let's get to it!

  1. If your platform does not already have Java installed, install it. You will need the SDK for Java 1.5+ (not just the JRE) in order to build and run the Shore Side Data System. For the OS X installation, it was already part of the OS, but if not, you will most likely retrieve it from http://java.sun.com. (The details of a Java installation are not listed here).
  2. Install Ant which can be retrieved from http://ant.apache.org/. Ant 1.7.0 was used during the development of these instructions. You will want to make sure that the bin directory of the Ant installation is in your path so that you can run 'ant' from any command line location.
  3. Install an instance of an Apache 2 web server. The scope of this installation is outside these instructions, but once you have the apache web server installed, make sure there is a directory where users can get http access to file and directory listings. All SSDS data files and generated products will be stored in some local directory. The idea is that you make that directory available through an HTTP server and all SSDS managed assets become available over HTTP. So once you have installed Apache and have a directory that can be browsed via http, remember the local directory location for later. For example, on the Mac, an Apache server is already installed and if you turn on Web Sharing, you can make your /Users/kgomes/Sites directory available via HTTP. So, I chose to create a directory in my Sites folder called ssdsdata that is then browseable via http://localhost/~kgomes/ssdsdata. So the directory to remember is: 
    content.directory.location=/Users/kgomes/Sites/ssdsdata
    TODO detail an installation of OPeNDAP on Apache

    It is helpful to add an OPeNDAP server to the apache server so some of the products can be served via OPeNDAP. I still need to document how to do that.

  4. The next thing to do is install version 4.2.2GA of JBoss. You can retrieve that from http://jboss.org. After you download the .ZIP file, you can simply unzip it to create a new jboss-4.2.2GA folder. For this example, I unzipped the file to /Applications on the Mac so my Jboss home directory is. You will want to make sure you have full write and execution permissions on this directory. 
    jboss.home=/Applications/jboss-4.2.2.GA
    Feel free to Run JBoss

    Just to make sure that JBoss will run OK, I usually like to run it once before building SSDS just to make sure it runs OK. Open a command prompt (terminal) and cd to the jboss home directory. Then run (at least on the Mac):

    sudo ./bin/run.sh

    A whole bunch of stuff should go by and eventually you should see something like:

    16:37:08,072 INFO  [Server] JBoss (MX MicroKernel) [4.2.2.GA (build: SVNTag=JBoss_4_2_2_GA date=200710221139)] Started in 9s:33ms

    This means JBoss is up and running. You can also browse to http://localhost:8080 and make sure you can view it through a browser. You can then shutdown JBoss by going back to the terminal window and typing Cntl-C.

  5. For Flex development, download and install the Adobe Flex SDK. You can download the SDK from http://opensource.adobe.com/wiki/display/flexsdk/Downloads. For this example, I installed it to the /Applications folder so I ended up with: 
    FLEX_HOME=/Applications/flex_sdk_3.3.0.4852
  6. Now you will need to setup the database server where you want the SSDS to store the metadata and data that it manages. These instructions show how to do it on a remote Microsoft SQL Server, but at some point, I will try to write up parallel instructions for MySQL. I will not go through the setup of the SQL Server, but once it is up and running, you will need to create two databases. For these instructions, I created 'SSDS_Data' and 'SSDS_Metadata'. Also, create an account that has database ownership on both and remember the following information for later: 
    database.server.name=database.host.name
database.server.login.username=dbo_username
database.server.login.password=dbo_password
  7. Check out the SSDS code base from Google Code.
    1. You will have to have a Google account to check out the code
    2. This step will depend on the subversion client you use, but as an example, here is how you would do it with command line as a project member (can make changes) 
      svn checkout https://shore-side-data-system.googlecode.com/svn/trunk/ shore-side-data-system --username jdoe

      A read-only checkout can happen anonymously like:

      svn checkout http://shore-side-data-system.googlecode.com/svn/trunk/ shore-side-data-system-read-only
      Ignore directories

      If you are using a GUI client for subversion that can ignore directories, you will want to ignore the following directories (they won't appear until you run ant):

      • build
      • dist
      • src/gen
  8. You should now have everything you need installed to get the SSDS up and running. The next step is to configure properties so that you can build and deploy the SSDS components to their various locations and then startup JBoss to start the SSDS. In order to configure the build to be appropriate for you configuration, you will need to create a custom.properties file in the root of the SSDS code base and set all the properties to match you installation. Fortunately, we have created a template that you can work from. Copy custom.properties.template to custom.properties and then edit the properties to match your configuration. Use the instructions in the template to help you define the properties correctly and you will need the information gathered above to complete the property configuration.
  9. During the custom.properties configuration, you defined various aspects for the LDAP security that will back the SSDS. You need to then define security roles (i.e. LDAP groups) in src/web/src/WEB-INF/web.xml 
    	<security-constraint>
		<web-resource-collection>
			<web-resource-name>login result page</web-resource-name>
			<url-pattern>/loginResult.jsp</url-pattern>
		</web-resource-collection>
		<auth-constraint>
			<!-- Place your LDAP groups that are authorized to login here -->
			<role-name>Engineering Distribution List</role-name>
			<role-name>Research Distribution List</role-name>
			<role-name>ITD Distribution List</role-name>
			<role-name>DMO Distribution List</role-name>
			<role-name>OED Distribution List</role-name>
		</auth-constraint>
	</security-constraint>
  10. Whew, once all that is done, you are ready to build and deploy the SSDS. Open command prompt, cd to directory where SSDS was checked out and type 
    ant -Dtarget=deploy
  11. Once the build is complete, open a terminal window, change directory to where the JBoss home is, and start JBoss 
    sudo ./bin/run.sh
  12. Once JBoss finishes startup, you should see the line: 
    17:12:41,607 INFO  [Server] JBoss (MX MicroKernel) [4.2.2.GA (build: SVNTag=JBoss_4_2_2_GA date=200710221139)] Started in 19s:45ms

    and hopefully you did not see any stack traces fly by during startup. If all looks OK, you should be able to go the SSDS_Metadata database and see newly created tables that will be where SSDS will store is metadata. You can also open a browser and go to http://localhost:8080/ssds-docs/ to see a simple page with some links to SSDS documentation and various utilities and libraries.

    Still to document
    1. Configure mod_jk in Apache/JBoss
    2. Configure SSL for login.jsp page

Setup an Eclipse project:

In order to actually do some development on the SSDS code base, you can use an IDE like Eclipse to edit the code and use ant to deploy your changes to JBoss. To setup an Eclipse project.

  1. Install eclipse that you download from http://www.eclipse.org
  2. Startup Eclipse and select File->New->Java Project.
  3. In the New Project Window, select 'Create project from existing source' and browse to where you checked out the SSDS source code. Once you configure the project correctly, you should have the following project settings:
    1. There should be two source directories: 
      src/java

      and

      src/gen

      (src/gen is created by ant during build)

  4. Add all jars in the lib directory
  5. Add src/resources/build/antlr/antlr-2.7.5.jar
  6. Add JBoss jars
    1. JBOSS_HOME/client/activation.jar
    2. JBOSS_HOME/client/servlet-api.jar
    3. JBOSS_HOME/client/jboss-j2ee.jar
    4. JBOSS_HOME/client/log4j.jar
    5. JBOSS_HOME/server/default/lib/commons-codec.jar
    6. JBOSS_HOME/server/default/lib/commons-collections.jar
    7. JBOSS_HOME/server/default/lib/commons-httpclient.jar
    8. JBOSS_HOME/server/default/lib/hibernate3.jar
    9. JBOSS_HOME/server/default/lib/mail.jar
  7. output set to build/classes (to align with ant's build files)

Create a FlexBuilder (plug-in) project:

  1. Start Eclipse with Flex-Builder plug-in installed
  2. File->New->Other..
  3. Select Flex Builder->Flex Project
  4. Type in 'ssds-flex' for name
  5. Uncheck 'Use default location'
  6. Browse to SSDS_HOME/src/web and select choose
  7. Select 'Web Application'
  8. Select 'J2EE' as Application Server Type
  9. Check Use remote object access service
  10. Click Next>
  11. Uncheck 'Use default location for Local LifeCycle Data Service server'
  12. Browse to SSDS_HOME/src/resources/build/flex and choose it for the 'Root folder'
  13. Change 'Root URL' to the URL of the servlet context (for example, on localhost it would be 'http://localhost:8080/servlet/')
  14. Change the 'Context Root'to '/servlet/'
  15. Select 'Compile Application Locally in Flex Builder'
  16. For 'Output folder location' put your deployment directory for the web application (for example /Users/kgomes/Applications/jboss-4.2.2.GA/server/default/deploy/ssds.war)
  17. Click Validate Configuration (it will warn that the output folder is not a subfolder of the server root (that is OK).
    Will create a Main.mxml

    Note that the creation of the Flex Builder project will create a Main.mxml file. To fix this, right click on explorer.mxml and choose 'Set As Default Application', then you can delete the Main.mxml file.

  18. Click on Finish

NOTE: To run the tests fully, you must have perl installed with the following module:

  1. Class-ObjectTemplate-0.7 (http://search.cpan.org/~jasons/Class-ObjectTemplate-0.7/)
Document generated by Confluence on Feb 04, 2026 08:56